Connecting to ArangoDB

Transport

The ArangoDB C#/.NET driver uses the IApiClientTransport interface to allow providing your own transport implementation. You might want to provide a customized transport to implement features such as:

• automated retries for failed requests
• automated failover to a backup ArangoDB instance
• load-balancing requests to multiple ArangoDB instances

Authentication[]

The HttpApiTransport class implements IApiClientTransport and is the standard HTTP transport provided by the driver. It supports the Basic Auth and JWT Authentication schemes.

Basic Auth

To create HttpApiTransport using Basic Auth, supply the appropriate base path and credentials to the static UsingBasicAuth method as follows:

var transport = HttpApiTransport.UsingBasicAuth(
    new Uri("http://localhost:8529/"),
    dbName,
    "username",
    "password");

JSON Web Token (JWT)

To create HttpApiTransport using JWT tokens, supply the appropriate base path and JWT token to the static UsingJWTAuth method as follows:

var transport = HttpApiTransport.UsingJwtAuth(
    new Uri("http://localhost:8529/"),
    dbName,
    jwtTokenString);

This assumes you already have a JWT token. If you need to get a token from ArangoDB, you need to first set up an HttpApiTransport without any credentials, submit a request to ArangoDB to get a JWT token, then call SetJwtToken on the transport. e.g.:

// Create HttpApiTransport with no authentication set
var transport = HttpApiTransport.UsingNoAuth(
  new Uri(arangodbBaseUrl),
  databaseName);
  
// Create AuthApiClient using the no-auth transport
var authClient = new AuthApiClient(transport);
// Get JWT token by submitting credentials
var jwtTokenResponse = await authClient.GetJwtTokenAsync("username", "password");
// Set token in current transport
transport.SetJwtToken(jwtTokenResponse.Jwt);
// Use the transport, which will now be authenticated using the JWT token. e.g.:
var databaseApi = new DatabaseApiClient(transport);
var userDatabasesResponse = await databaseApi.GetUserDatabasesAsync();

Depending on your application’s needs, you might want to securely store the token somewhere so you can use it again later. ArangoDB’s tokens are valid for a one-month duration, so you will need to get a new token at some point. You must handle fetching new tokens and setting them on the transport instance as part of your application.

ArangoDBClient

ArangoDBClient is a wrapper around all of the individual API client classes. By instantiating ArangoDBClient once, you have access to instances of each API client class. With an instance of IApiClientTransport, create ArangoDBClient as follows:

var adb = new ArangoDBClient(transport);

Now you can access instances of the individual client classes as properties, e.g.:

// Create a new collection named "TestCollection"
var postCollectionResponse = await adb.Collection.PostCollectionAsync(
  new PostCollectionBody {
    Name = "TestCollection"
  });
// Add a document to "TestCollection"
var docResponse = await adb.Document.PostDocumentAsync(
  "TestCollection", 
  new { TestKey = "TestValue" });

API Client Method Signatures

A typical method signature is as follows:

// This is illustrative, not actually a method in the API
apiClient.PostEntity(string pathParam, PostEntityBody body, PostEntityQuery query = null);

• Path parameters are always exposed as string arguments and come first in the argument list. e.g., pathParam in the example above.
• An API model class is used when an endpoint expects some body content. An instance of the API model is expected as an argument to the method. This comes after any path arguments. e.g., PostEntityBody instance in the example above.
• Optional parameters are exposed as nullable properties. In cases where the body content is an ArangoDB-specific object, properties with null values are ignored and not sent in the request to ArangoDB. In cases where the body content is a user-specified object (e.g., a document or edge document), null values are not ignored.
• Where query parameters can be used, a class captures all possible query parameters. e.g., PostEntityQuery instance in the example above.
• The query argument is left optional with a default value of null. If no query argument is provided, no query string is included in the request to ArangoDB.
• Properties of the query class are nullable, and properties of the query class with null values are not included in the request to ArangoDB.

 

Help us improve

Anything unclear or buggy in this tutorial? Provide Feedback